<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>S-XML</title>
  <link rel="stylesheet" type="text/css" href="style.css"/>
  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
</head>

<body>
  <div class="header">
    <h1>S-XML</h1>
  </div>

  <p>
    S-XML is a simple XML parser implemented in Common Lisp.
    Originally it was written by <a href="http://homepage.mac.com/svc">Sven Van Caekenberghe</a>.
    It is now being maintained by <a href="http://homepage.mac.com/svc">Sven Van Caekenberghe</a>,
    <a href="http://constantly.at">Rudi Schlatte</a> and <a href="http://www.cs.indiana.edu/~bmastenb">Brian Mastenbrook</a>.
    S-XML is used by <a href="http://common-lisp.net/project/s-xml-rpc">S-XML-RPC</a> and
    <a href="http://common-lisp.net/project/cl-prevalence">CL-PREVALENCE</a>.
  </p>

  <p>
    This XML parser implementation has the following features:
  </p>
  <ul>
    <li>It works (handling many common XML usages).</li>
    <li>It is very small (the core is about 400 lines of code, including comments and whitespace).</li>
    <li>It has a core API that is simple, efficient and pure functional, much like that from <a href="http://pobox.com/~oleg/ftp/Scheme/xml.html">SSAX</a> (see also <a href="http://ssax.sourceforge.net">http://ssax.sourceforge.net</a>).</li>
    <li>It supports different DOM models: an <a href="http://pobox.com/~oleg/ftp/Scheme/SXML.html">XSML</a>-based one, an <a href="http://opensource.franz.com/xmlutils/xmlutils-dist/pxml.htm">LXML</a>-based one and a classic xml-element struct based one.</li>
    <li>It is reasonably time and space efficient (internally avoiding garbage generatation as much as possible).</li>
  </ul>
  <p>
    This XML parser implementation has the following limitations:
  </p>
  <ul>
    <li>It does not support CDATA.</li>
    <li>Only supports simple character sets.</li>
    <li>It does not support name spaces</li>
    <li>It does not support any special tags (like processing instructions).</li>
    <li>It is not validating, even skips DTD's all together.</li>
  </ul>

<h3>Download</h3>
<p>
  You can download the LLGPL source code and documentation as <a href="s-xml.tgz">s-xml.tgz</a> 
  (signature: <a href="s-xml.tgz.asc">s-xml.tgz.asc</a> for which the public key can be found 
  in the <a href="http://common-lisp.net/keyring.asc">common-lisp.net keyring</a>) 
  (build and/or install with ASDF). 
</p>
<p>
  You can view the <a href="http://common-lisp.net/cgi-bin/viewcvs.cgi/?cvsroot=s-xml">CVS Repository</a> or
  get anonymous CVS access as follows:
  <pre>$ cvs -d:pserver:anonymous@common-lisp.net:/project/s-xml/cvsroot login
(Logging in to anonymous@common-lisp.net)
CVS password: anonymous
$ cvs -d:pserver:anonymous@common-lisp.net:/project/s-xml/cvsroot co s-xml</pre>
</p>

<h3>API</h3>
<p>
  The plain API exported by the package S-XML (automatically generated by LispDoc) 
  is available in <a href="S-XML.html">S-XML.html</a>.
</p>

<h3>XML Parser</h3>
<p>
  Using a DOM parser is easier, but usually less efficient: see the next sections. To use the event-based API of the parser, you call the function start-parse-xml on a stream, specifying 3 hook functions:
</p>
<ul>
  <li><b>new-element-hook</b> <tt>(name attributes seed) =&gt; seed</tt><br/> 
    Called when the parser enters a new element. 
    The name of the element (tag) and the attributes (an unordered dotted pair list of attribute names as keywords 
    and attribute values as strings) of the element are passed in, 
    as well as the seed from the previous element (either the last encountered sibling or the parent). 
    The hook must return a seed value to be passed to the first child element 
    or directly to finish-element-hook (when there are no children).</li>
  <li><b>finish-element-hook</b> <tt>(name attributes parent-seed seed) =&gt; seed</tt><br/> 
    Called when the parser leaves an element. 
    The name of the element (tag) and the attributes (an unordered dotted pair list of attribute names as keywords 
    and attribute values as strings) of the element are passed in, 
    as well as the parent-seed, the seed passed to us when this element started,
    i.e. passed to our corresponding new-element-hook,
    as well as the seed from the previous element (either the last encountered sibling or the parent). 
    The hook must return the final seed value for this element
    to be passed to the next sibling or to the parent (when there are no more children).</li>
  <li><b>text-hook</b> <tt>(string seed) =&gt; seed</tt><br/> 
    Called when the parser finds text as contents. 
    The string of the text encountered is passed in, as well as the seed from the previous element
    (either the last encountered sibling or the parent).
    The hook must return the final seed value for this element
    to be passed to the next sibling or to the parent (when there are no more children).</li>
</ul>      
<p>
  As an example, consider the following tracer that shows how the different hooks are called:
</p>
<pre>(defun trace-xml-new-element-hook (name attributes seed)
  (let ((new-seed (cons (1+ (car seed)) (1+ (cdr seed)))))
    (trace-xml-log (car seed) 
                   "(new-element :name ~s :attributes ~:[()~;~:*~s~] :seed ~s) =&gt; ~s" 
                   name attributes seed new-seed)
    new-seed))

(defun trace-xml-finish-element-hook (name attributes parent-seed seed)
  (let ((new-seed (cons (1- (car seed)) (1+ (cdr seed)))))
    (trace-xml-log (car parent-seed)
                   "(finish-element :name ~s :attributes ~:[()~;~:*~s~] :parent-seed ~s :seed ~s) =&gt; ~s" 
                   name attributes parent-seed seed new-seed)
    new-seed))

(defun trace-xml-text-hook (string seed)
  (let ((new-seed (cons (car seed) (1+ (cdr seed)))))
    (trace-xml-log (car seed) 
                   "(text :string ~s :seed ~s) =&gt; ~s" 
                   string seed new-seed)
    new-seed))

(defun trace-xml (in)
  "Parse and trace a toplevel XML element from stream in"
  (start-parse-xml in
		   (make-instance 'xml-parser-state
				  :seed (cons 0 0) 
                                  ;; seed car is xml element nesting level
                                  ;; seed cdr is ever increasing from element to element
				  :new-element-hook #'trace-xml-new-element-hook
                                  :finish-element-hook #'trace-xml-finish-element-hook
				  :text-hook #'trace-xml-text-hook)))</pre>
<p>
  This is the output of the tracer on two small XML documents, the seed is a CONS that keeps track of the nesting level in its CAR and of its flow through the hooks with an ever increasing number is its CDR:
</p>
<pre>S-XML 31 &gt; (with-input-from-string (in "&lt;FOO X='10' Y='20'&gt;&lt;P&gt;Text&lt;/P&gt;&lt;BAR/&gt;&lt;H1&gt;&lt;H2&gt;&lt;/H2&gt;&lt;/H1&gt;&lt;/FOO&gt;") (trace-xml in))
(new-element :name :FOO :attributes ((:Y . "20") (:X . "10")) :seed (0 . 0)) =&gt; (1 . 1)
  (new-element :name :P :attributes () :seed (1 . 1)) =&gt; (2 . 2)
    (text :string "Text" :seed (2 . 2)) =&gt; (2 . 3)
  (finish-element :name :P :attributes () :parent-seed (1 . 1) :seed (2 . 3)) =&gt; (1 . 4)
  (new-element :name :BAR :attributes () :seed (1 . 4)) =&gt; (2 . 5)
  (finish-element :name :BAR :attributes () :parent-seed (1 . 4) :seed (2 . 5)) =&gt; (1 . 6)
  (new-element :name :H1 :attributes () :seed (1 . 6)) =&gt; (2 . 7)
    (new-element :name :H2 :attributes () :seed (2 . 7)) =&gt; (3 . 8)
    (finish-element :name :H2 :attributes () :parent-seed (2 . 7) :seed (3 . 8)) =&gt; (2 . 9)
  (finish-element :name :H1 :attributes () :parent-seed (1 . 6) :seed (2 . 9)) =&gt; (1 . 10)
(finish-element :name :FOO :attributes ((:Y . "20") (:X . "10")) :parent-seed (0 . 0) :seed (1 . 10)) =&gt; (0 . 11)
(0 . 11)

S-XML 32 &gt; (with-input-from-string (in "&lt;FOO&gt;&lt;UL&gt;&lt;LI&gt;1&lt;/LI&gt;&lt;LI&gt;2&lt;/LI&gt;&lt;LI&gt;3&lt;/LI&gt;&lt;/UL&gt;&lt;/FOO&gt;") (trace-xml in))
(new-element :name :FOO :attributes () :seed (0 . 0)) =&gt; (1 . 1)
  (new-element :name :UL :attributes () :seed (1 . 1)) =&gt; (2 . 2)
    (new-element :name :LI :attributes () :seed (2 . 2)) =&gt; (3 . 3)
      (text :string "1" :seed (3 . 3)) =&gt; (3 . 4)
    (finish-element :name :LI :attributes () :parent-seed (2 . 2) :seed (3 . 4)) =&gt; (2 . 5)
    (new-element :name :LI :attributes () :seed (2 . 5)) =&gt; (3 . 6)
      (text :string "2" :seed (3 . 6)) =&gt; (3 . 7)
    (finish-element :name :LI :attributes () :parent-seed (2 . 5) :seed (3 . 7)) =&gt; (2 . 8)
    (new-element :name :LI :attributes () :seed (2 . 8)) =&gt; (3 . 9)
      (text :string "3" :seed (3 . 9)) =&gt; (3 . 10)
    (finish-element :name :LI :attributes () :parent-seed (2 . 8) :seed (3 . 10)) =&gt; (2 . 11)
  (finish-element :name :UL :attributes () :parent-seed (1 . 1) :seed (2 . 11)) =&gt; (1 . 12)
(finish-element :name :FOO :attributes () :parent-seed (0 . 0) :seed (1 . 12)) =&gt; (0 . 13)
(0 . 13)</pre>
<p>
  The following example counts tags, attributes and characters:
</p>
<pre>(defclass count-xml-seed ()
  ((elements :initform 0)
   (attributes :initform 0)
   (characters :initform 0)))

(defun count-xml-new-element-hook (name attributes seed)
  (declare (ignore name))
  (incf (slot-value seed 'elements))
  (incf (slot-value seed 'attributes) (length attributes))
  seed)

(defun count-xml-text-hook (string seed)
  (incf (slot-value seed 'characters) (length string))
  seed)
  
(defun count-xml (in)
  "Parse a toplevel XML element from stream in, counting elements, attributes and characters"
  (start-parse-xml in
		   (make-instance 'xml-parser-state
				  :seed (make-instance 'count-xml-seed)
				  :new-element-hook #'count-xml-new-element-hook
				  :text-hook #'count-xml-text-hook)))

(defun count-xml-file (pathname)
  "Parse XMl from the file at pathname, counting elements, attributes and characters"
  (with-open-file (in pathname)
    (let ((result (count-xml in)))
      (with-slots (elements attributes characters) result
        (format t 
  "~a contains ~d XML elements, ~d attributes and ~d characters.~%"
                pathname elements attributes characters)))))</pre>
<p>
  This example removes XML markup:
</p>
<pre>(defun remove-xml-markup (in)
  (let* ((state (make-instance 'xml-parser-state
                              :text-hook #'(lambda (string seed) (cons string seed))))
         (result (start-parse-xml in state)))
    (apply #'concatenate 'string (nreverse result))))</pre>
<p>
  The next example is from the xml-element struct DOM implementation, where the SSAX parser hook functions are building the actual DOM:
</p>
<pre>(defun standard-new-element-hook (name attributes seed)
  (declare (ignore name attributes seed))
  '())

(defun standard-finish-element-hook (name attributes parent-seed seed)
  (let ((xml-element (make-xml-element :name name
				       :attributes attributes
				       :children (nreverse seed))))
    (cons xml-element parent-seed)))

(defun standard-text-hook (string seed)
  (cons string seed))

(defmethod parse-xml-dom (stream (output-type (eql :xml-struct)))
  (car (start-parse-xml stream
			(make-instance 'xml-parser-state
				       :new-element-hook #'standard-new-element-hook
				       :finish-element-hook #'standard-finish-element-hook
				       :text-hook #'standard-text-hook))))
</pre>
<p>
  The parse state can be used to specify the initial seed value (nil by default), and the set of known entities (the 5 standard entities (lt, gt, amp, qout, apos) and nbps by default).
</p>
<h3>DOM</h3>
<p>
  Using a DOM parser is easier, but usually less efficient. Currently three different DOM's are supported:
</p>
<ul>
  <li>The DOM type <tt>:sxml</tt> is an <a href="http://pobox.com/~oleg/ftp/Scheme/SXML.html">XSML</a>-based one</li>
  <li>The DOM type <tt>:lxml</tt> is an <a href="http://opensource.franz.com/xmlutils/xmlutils-dist/pxml.htm">LXML</a>-based one</li>
  <li>The DOM type <tt>:xml-struct</tt> is a classic xml-element struct based one</li>
</ul>
<p>
There is a generic API that is identical for each type of DOM, with an extra parameter <tt>input-type</tt> or <tt>output-type</tt> used to specify the type of DOM. The default DOM type is <tt>:lxml</tt>. Here are some examples:
</p>
<pre>? (in-package :s-xml)
#&lt;Package "S-XML"&gt;

? (setf xml-string "&lt;foo id='top'&gt;&lt;bar&gt;text&lt;/bar&gt;&lt/foo&gt;")
"&lt;foo id='top'&gt;&lt;bar&gt;text&lt;/bar&gt;&lt;/foo&gt;"

? (parse-xml-string xml-string)
((:|foo| :|id| "top") (:|bar| "text"))

? (parse-xml-string xml-string :output-type :sxml)
(:|foo| (:@ (:|id| "top")) (:|bar| "text"))

? (parse-xml-string xml-string :output-type :xml-struct)
#S(XML-ELEMENT :NAME :|foo| :ATTRIBUTES ((:|id| . "top"))
               :CHILDREN (#S(XML-ELEMENT :NAME :|bar|
                                         :ATTRIBUTES NIL
                                         :CHILDREN ("text"))))

? (print-xml * :pretty t :input-type :xml-struct)
&lt;foo id="top"&gt;
  &lt;bar&gt;text&lt;/bar&gt;
&lt;/foo&gt;
NIL

? (print-xml '(p "Interesting stuff at " ((a href "http://slashdot.org") "SlashDot")))
&lt;P&gt;Interesting stuff at &lt;A HREF="http://slashdot.org"&gt;SlashDot&lt/A&gt;&lt/P&gt;
NIL</pre>
<p>
  Tag and attribute names are converted to keywords. Note that XML is case-sensitive, hence the fact that Common Lisp has to resort to the special literal symbol syntax.
</p>

<h3>Release History and ChangeLog</h3>

<pre>
2005-02-03 Sven Van Caekenberghe &lt;svc@mac.com&gt;

        * release 5 (cvs tag RELEASE_5)
	* added :start and :end keywords to print-string-xml
	* fixed a bug: in a tag containing whitespace, like &lt;foo&gt; &lt;/foo&gt; the parser collapsed 
	  and ingnored all whitespace and considered the tag to be empty!
          this is now fixed and a unit test has been added
	* cleaned up xml character escaping a bit: single quotes and all normal whitespace  
	  (newline, return and tab) is preserved a unit test for this has been added
	* IE doesn't understand the &apos; XML entity, so I've commented that out for now. 
	  Also, using actual newlines for newlines is probably better than using #xA, 
	  which won't get any end of line conversion by the server or user agent.

June 2004 Sven Van Caekenberghe &lt;svc@mac.com&gt;

	* release 4
	* project moved to common-lisp.net, renamed to s-xml, 
	* added examples counter, tracer and remove-markup, improved documentation

13 Jan 2004 Sven Van Caekenberghe &lt;svc@mac.com&gt;
	
	* release 3
	* added ASDF systems
	* optimized print-string-xml

10 Jun 2003 Sven Van Caekenberghe &lt;svc@mac.com&gt;
	
	* release 2
	* added echo-xml function: we are no longer taking the car when
	  the last seed is returned from start-parse-xml

25 May 2003 Sven Van Caekenberghe &lt;svc@mac.com&gt;
	
	* release 1
	* first public release of working code
	* tested on OpenMCL
	* rewritten to be event-based, to improve efficiency and 
	  to optionally use different DOM representations
	* more documentation

end of 2002 Sven Van Caekenberghe &lt;svc@mac.com&gt;
	
	* release 0
	* as part of an XML-RPC implementation
</pre>

<h3>Todo</h3>

<ul>
  <li>Some should find some time to add CDATA support (both in the parser and as a print function) - this shouldn't be too hard, and it would be really useful!</li>
</ul>

<h3>Mailing Lists</h3>

<ul>
  <li><a href="http://common-lisp.net/mailman/listinfo/s-xml-cvs">S-XML-CVS mailing list info</a></li>
  <li><a href="http://common-lisp.net/mailman/listinfo/s-xml-devel">S-XML-DEVEL mailing list info</a></li>
  <li><a href="http://common-lisp.net/mailman/listinfo/s-xml-announce">S-XML-ANNOUNCE mailing list info</a></li>
</ul>

  <p>CVS version $Id: index.html,v 1.10 2005/02/03 08:36:05 scaekenberghe Exp $</p>

  <div class="footer">
    <p>Back to <a href="http://common-lisp.net/">Common-lisp.net</a>.</p>  
  </div>
  
  <div class="check">
    <a href="http://validator.w3.org/check/referer">Valid XHTML 1.0 Strict</a>
    <a href="http://jigsaw.w3.org/css-validator/check/referer">Valid CSS</a>
  </div>
</body>
</html>
